Definitions of Terminology


Song
Within this system, this indicates background music or sound effects.


Song Data
MIDI data created in a standard MIDI format. (See: Song ). Or, data that has been converted by an mks4agb system so that MIDI data can be used on a sound driver.


Waveform Data
Waveform data in AIFF (Audio Interchange File Format).
Or, data that has been converted by an mks4agb system so that AIFF data can be used on a sound driver.


Priority
When a song is about to be played in excess of the maximum number of simultaneously produced sounds, these values are used to determine which sounds to prioritize and produce. These can be set for each song and track and those totals become the priorities for the tracks themselves.


agb_c2s.bat
This is a sample program batch file supplied with the Game Boy Advance Developers Kit 2.0.


Music Player
Music Player can be equated to a playback device for playing song data and is a unique term used with the sound driver itself. More than one can be used and the operating area for each Music Player is set aside in the RAM. Two songs cannot be played simultaneously on a single player. Generally, one will be used for background music while three others are used for sound effects.


Clock
This is the pulse unit used in the timing control of the sequencer.
In this sound driver, a quarter note is composed of 24 clocks.


MIDI Code
In this manual, MIDI codes are shown as follows:
Dollar Sign $ (hexadecimal format): Status Byte (i.e.,. $Bx, $Cx, $Ex
Other (decimal format): Data byte. For example, the status byte in $Bx, 30, 9 would be $Bx, while the data bytes would be 30 and 9.


System Configuration Files


mks4agb.exe
Sound Object Automatic Creation Program


mks4agb.ini
Sound Object Creation Set Up File


aif2agb.exe
Converter that changes {wavename}.aif files to {wavename}.s files.


mid2agb.exe
Converter that changes {songname}.mid files to {songname}.s files.


MusicPlayDef.s
Source file included in each set of song data. It is automatically included.


mks4agbLib.h
Source include file for incorporation into games.


mks4agbLib.o
Source library code for incorporation into games.


m4aLibOD1.o
Source library code when ONLY DMA1 is selected.


m4aLibUSC.o
Source library code when SYS_ROM is selected.


SoundMon.o
Simple Monitor Object File (Main Module)


crt0.o
Simple Monitor Object File (Parts Module)


Simple Monitor Displays



SONG (Control Pad : Press Left/Right to change song numbers)
Song number to be played with Music Player. This number is set by mks4agb.ini.
While the song number is changing, the number blinks. If you press A Button, the music starts, and the blinking stops.
If you press the B Button while a number is blinking, it goes back to the previous song number before the blinking started, the music stops, and the blinking stops too.


PLY (Control Pad : Select using Up/Down)
The number of the Music Player which song selected in SONG column uses. It is only a display, and you cannot change it.
The elements of PLY,VGR,VOL, PRI, and TRACK correspond to the song being played.


VGR (Cannot be changed.)
The figures in this column are the numbers of the tone color group which the song selected in the SONG column uses.
It is only a display, and you cannot change it.


VOL (Cannot be changed.)
The figures in this column are the master volume values of the song selected in the SONG column.
It is only a display, and you cannot change it.


PRI (Cannot be changed.)
The figures in this column are the values for priority of the song selected in the SONG column.
It is only a display, and you cannot change it.


TRACK (Cannot be changed.)
Number of tracks of song being played/Number of tracks set aside by Music Player
When play stops,the number of tracks of the song being played blinks.
If playing of the song has already been stopped, when it is changing the song number, it displays a zero for number of tracks of the song being played
Both numerator and denominator are a display only, and you cannot change them.


REVERB(Control Pad: Select with Up or Down or change the Value with Left or Right.)
This is the reverb value. Reverb will be applied to all of the sounds output using the direct sound function. Reverb cannot be applied to the Music Players individually.
Also, reverb cannot be used on sounds output from CGB compatible sound.
The reverb range is from 0 to 127. When a song has been started in the SONG column, if reverb is set for the song, it is linked with this.  


CHN(Control Pad : Up/Down to Select, Left/Right to Change)
The figure on the left side is the number of channels currently in use by direct sound. It is only a display and cannot be changed. The figure on the right is the maximum number of simultaneously produced sounds. Use Left/Right on the Control Pad to adjust between 1~12. If you make this value larger, the process slows down. Please reference in situations where you have to limit the number of simultaneously produced sounds during a game due to processing time.


FREQ(Control Pad: Select with Up or Down and change the Value with Left or Right.)
This is the sound driver playback frequency. The following values can be selected:
   5734 Hz,  7884 Hz, 10512 Hz, 13379 Hz, 15768 Hz, 18157 Hz,
  21024 Hz, 26758 Hz, 31536 Hz, 36314 Hz, 40137 Hz, 42048 Hz.


D/A BIT(Control Pad: Select with Up or Down and change the Value with Left or Right.)
This is the final output DA conversion bit number. It can be changed using Right/Left on the Control Pad.


SIZE (Cannot Change )
The total size of all sound objects incorporated into the game.


LINES (SELECT : Reset)
The figure on the left side is the average value for every 0.25 seconds of processing time for each V-SYNC of sound related functions. If this value is 228, it means that 100% of the CPU's processing time is being used by sound related functions. It is only a display and cannot be changed. The figure on the right side is the maximum value from a reset to the present processing time for each V-SYNC. By pressing SELECT you can do a reset.


MIDI:VGR (Control Pad : Select using Up or Down and change the Value with Left or Right.)
The tone color group number used with MIDI input performance. You can change this value with Left/Right on the Control Pad, but this change is enabled only from when the MIDI program change($Cx) is performed.


:VOL (Control Pad : Select using Up or Down and change the Value with Left or Right.)
Value for master volume of MIDI input performance. You can change this value with Left/Right on the Control Pad.


:PRI (Control Pad : Select using Up or Down and change the Value with Left or Right.)
Value for priority of MIDI input performance. You can change this value with Left/Right on the Control Pad.



System Configuration Directories


Work Directory
This is a newly allotted directory which serves as a reference position when developing sound object groups. A separate directory must be allotted for each game.
In the example used in the tutorial in this manual, it is C:\Mks4agb.


Waveform Data Input Directory
This is the directory where waveform data files created by the user are placed.
This refers to the settings (aif_dir) made in mks4agb.ini.
More Info(Link to the mks4agb System Manual.)


Song Data Input Directory
This is the directory where song data files created by the user are placed.
This refers to the settings (mid_dir) made in mks4agb.ini.
More Info(Link to the mks4agb System Manual)


Source File Directory
This is the directory where .s file groups are output after running mks4agb.exe.
This refers to the settings (src_dir) made in mks4agb.ini.
More Info(Link to the mks4agb System Manual)


Output Directory
This is the directory where sound object groups are output after running mks4agb.exe.
This refers to the settings (out_dir) made in mks4agb.ini.
All files output to this directory will be passed to the main program side.
More Info(Link to the mks4agb System Manual.)


mks4agb.ini Parameters


Rebuild Switch (mks4agb.ini : rebuild)
This is a parameter for building (Make function) sound objects when running mks4agb.exe.
Normally it is "0," but when rebuilding (Make all), it is set to "'1."
More Info (Link to the mks4agb System Manual.)



AGB System Library File Directory (mks4agb.ini : agb_lib)
This is the directory for the library file group provided with the Game Boy Advance Developer ToolKit 2.4. When set up according to the toolsSetup.txt file included with this kit, the location will be {Drive Name}:\agb\lib.
More Info (Link to the mks4agb System Manual.)



GCC Execution Path (mks4agb.ini : cmd_path)
This is the execution path for GCC and other compilers. When set up according to the toolSetup.txt file in the Game Boy Advance Developer ToolKit 2.4, the directory will be in the path specified in agb_c2s.bat. (thumbelf is specified.)
More Info (Link to the mks4agb System Manual.)



Initial Set Up Values for Sound Modes (mks4agb.ini : mode_i)
The sound modes are specified when the sound functions begin. The sound modes include; the number of simultaneously produced direct sounds, the master volume of direct sounds, the playback frequency of direct sounds, and the number of final output DA conversion bits. The initialization values of each of these can be specified.
More Info (Link to the mks4agb System Manual.)



Starting Tone Color Group Setup (mks4agb.ini : vgroup)
The tone colors set up are gathered into groups and the tone color group to be used for each song is specified. Dividing them into groups makes it possible to have more tone color settings.
(This is because the tone color numbers from 0 ~ 127 can be used for each group.)
More Info (Link to the mks4agb System Manual.)



Tone Color Setup (mks4agb.ini : p???)
Tone Color settings may be specified from 0 ~ 127 for each of the tone color groups. It is possible to specify a different tone color by changing a single parameter in a unit of sample waveform data. Since compatible sounds and direct sounds are set up differently, use precaution.
More Info (Link to the mks4agb System Manual.)



Key Split Table Setup (mks4agb.ini : t???)
When the "Key Split Tone Color" of the tone color settings is selected, the information shown in the links below will be referred to.
More Info (Link to the mks4agb System Manual - Key Split Table Settings)
More Info (Link to the mks4agb System Manual - Key Split Tone Color Setup)



Sound 3 Waveform Setup (mks4agb.ini : w???)
With AGB, you can choose between 32 steps and 64 steps using the "Specify Sound 3 Waveform RAM Data Combination Settings".  However, this sound driver can only handle 32 steps. This means that waveforms will be written with 32-character hexadecimals.
More Info (Link to the mks4agb System Manual.)



Music Player Setup (mks4agb.ini : mp??)
This is where the number of Music Players to be used during a game and the number of tracks for those music players is declared.
More Info (Link to the mks4agb System Manual)



Song Setup (mks4agb.ini : s???)
This is where the song number, tone color group, and priority are set for each song. When a song begins during a game, the identified song numbers will be specified here.
More Info (Link to the mks4agb System Manual)



MIDI Input Performance Setup (mks4agb.ini : pbymidi)
Turning this switch ON sends MIDI data from a keyboard or other device directly into a MIDI input-compatible cartridge. This makes it possible to output sound while having the characteristics specified in the .ini file from an AGB device. In other words, turning the switch ON enables one to compose music while playing it with the desired tone color. Song data cannot be created in real-time while performing.
More Info (Link to the mks4agb System Manual)


Memory Access Area Size (mks4agb.ini : memacc_s)
In this system, you can write data to a special RAM area by placing a MEMACC instruction in the song data. Designate the size of this RAM area to be between 0~255.
(Default Value: 16)
More Info( Link to the mks4agb System Manual)



Maximum Lines for Processing Time of m4aSoundMain( ) (mks4agb.ini : max_line)
The processing time for m4aSoundMain( ) for each 1/60 second frame is limited by the number of scan lines. The setting value is the "processing time" and not the "location of the scan lines to stop processing".  It is impossible to accurately limit time so in actuality, the setting value is exceeded by a certain number of lines. If a "0" is set, this function has no effect.
More Info (Link to the mks4agb System Manual)



DMA Limit Switch (mks4agb.ini : only_dma1)
This system normally uses 2 channels for the AGB/DMA function. When a value other than 0 is set here, it will only use one channel. Then the output of the direct sound becomes monaural, but the processing time becomes faster. If a programmer requests, enable this switch.
More Info (Link to the mks4agb System Manual)



System ROM Use Switch (mks4agb.ini : sys_rom)
By setting this to a value other than 0 the sound code in the system ROM is used and the code in Game Pak ROM and internal RAM can be minimized. However, be aware that with versions that do not use system ROM, there are limitations and differences in functionality.
More Info (Link to the mks4agb System Manual)




Input Data Files (Created by User)


{wavename}.aif
Waveform Data File.(AIFF Format)


{songname}.mid
Song Data File.(Standard MIDI Format)(See: Song Data)



Output Files(After running mks4agb.exe.)


Source File
The input data is converted into .s files(*.s).


{wavename}.s(Source File)
{wavename}.aif files converted using aif2agb.exe.


{songname}.s(Source File)
{songname}.midfiles converted using mid2agb.exe.


SoundDat.s(Source File)
Other automatically generated data(tone color, song tables, etc.)


MPlayDef.s(Source File)
Song Data Include Files


SndMonDat.s(Source File)
Data used with Simple Monitor.


Sound Objects
Files passed over to the main programmer(s).


{wavename}.o(Sound Objects)
Waveform data object files.


{songname}.o(Sound Objects)
Song data object files.


SoundDat.o(Sound Objects)
Other data object files.


m4aLib.o(Sound Objects)
Library code used when incorporating to games.


m4aLib.h(Sound Objects)
Include files used when incorporating to games.


SoundFiles(Sound Objects)
List of all sound object files.
This is included and used with Makefile of the main program.


Items Created in Working Directory


SoundMon.map
Simple Monitor .map file.


SoundMon.elf
Simple Monitor .elf file(Executable file)


SndMonDat.o
Object File for Simple Monitor Data


.s File Contents


Wxx
Wait xxclocks before executing the next command. This can be thought of as a "rest."
xx is a two-digit, single-byte number from 00-96, but the numbers do not always have to be in sequence.
(Values not defined in MusicPlayDef.s cannot be used.)
Note: The length of a quarter rest is 24 clocks; that of a whole rest is 96 clocks.


FINE
Pronounced "feeneh". This ends the track.


GOTO, label
Unconditional jump to the label position.(labels are 4 bytes.)


PATT, label
Calls a label pattern. Can be nested up to three times.


PEND
Ends the pattern, calls and restores to original state. If there is no call from anywhere, it will be ignored.


REPT, xx, label
Repeats from the label position to this point xx times. (xx is from 0 to 255).
Setting xx to "0" results in endless repeating (same as GOTO). It cannot be nested.
(Note: This command cannot be specified on a MIDI sequencer.)


TEMPO, xx/2
This sets the tempo for the entire song.(xx is from 2 to 510).


KEYSH, xx
This shifts the key of the track in question.(xx is from -128 to +127).
(Note: This command cannot be specified on a MIDI sequencer.)


MEMACC, mem_set, adr, dat
1 byte of data is written to the Memory Access Area.


PRIO, xx
When this value is added to the priority of a song, it becomes the priority of that track.
(The xx range is 0 to 255 when editing directly in an .s file or 0 to 127 when input using a MIDI sequencer.)


VOICE, xx
Selects the tone color. (xx is from 0 to 127). The tone color specified in mks4agb.ini will be selected. 


VOL, xx
Track Volume(xx is 0 to 127) Note: In order to make the master volume song setup valid, xx has to be specified using the formula [Value * {songname}_mvl/mxv].


PAN, c_v+xx
Panpot of a track.(xx is from -64 to +63) Note: Due to hardware limitations with CGB compatible sound, there are just three stages: right, middle and left.


BEND, c_v+xx
The bending of a pitch on a track.(xx is from -64 to +63).


BENDR, xx
Bending Range(xx is 0 to 127) This establishes the maximum width of the pitch bending, so it is expressed in half tones. Immediately after starting, the value is "2." That is, when the value of the pitch bending is maximized, it goes up (or down) a whole step.


LFOS, xx
Low Frequency Oscillator Speed(xx is from 0 to 127). This is the modulation speed. The higher the value, the higher the speed.


LFODL, xx
The time from "key on" until the LFO takes effect(xx is from 0 to 127). When this value is something other than "0", modulation and other effects will not work immediately following "key on." It takes effect after xxclocks have passed.


MOD, xx
Modulation Depth(xx is from 0 to 127)


MODT, xx
This is the type of modulation. xx has the following three values. "0" is vibrato(scale modification), "1" is tremolo (volume modification) and "2" is pan(normal position).
Immediately after starting, this value is "0"(scale modification).
TUNE, c_v+xx
Tuning(xx is from -64 to +63) The pitch of a track may be fine-tuned in ±(half tone) increments.


Nxx [ ,key [ ,velo [ ,gtp? ] ] ]
A "note" specifying a gate time of xx clocks. xx is a two-digit, single-byte number from 00 to 96, but it does not necessarily have to be in sequence.(Values not defined in MusicPlayDef.s cannot be used.)The length of a quarter note is 24 clocks; that of a whole note is 96 clocks.
More Info(Link to mks4agb System Manual.)


TIE [ ,key [ ,velo] ]
This is a tied note. The note will continue until there is an "EOT".
key refers to the scale, from CnM2 to Gn8, and velo is the velocity from v000 to v127.


EOT [ ,key ]
This command ends a tied note. key is the scale of the note to be stopped from CnM2 to Gn8.


XCMD, xIECV, xx
The volume of a pseudo-echo.(xx is from 0 to 127). A psuedo-echo is a function which maintains a note, following its production and release, at a specific volume and for a specific length of time.
This allows an echoing effect to be added to a track.
The echo will remain at a volume that is xx/127 of the volume of the note.


XCMD, xIECL, xx
Pseudo-Echo Length(xx is from 0 to 127). The pseudo-echo will remain for a period of xx/60 seconds.